These commands are illegal when the file is opened in Binary
mode.
In Binary mode, three numeric values of size double will be
read and returned as a vector.
This function is illegal in Binary mode.
This command is illegal in Binary mode.
File Object Agent
The LScript File Object Agent provides access to an operating system's disk file
management functionality. The LScript built-in command File() returns
an object of this type. Once assigned to a variable, the following File
Object Agent methods can be accessed through the host variable:isOpen
Returns a boolean value indicating that the file is indeed
open and accessible.
isOpen(void)
open
Opens a new file with a specified mode. The newly opened file
is assigned to the existing File Object Agent.
void open(name, // string; disk file
// to open
mode) // string; mode to use for
// open
reopen
Closes the currently open file, and reopens it in the
specified mode.
void reopen(mode) // string; mode to use for
// file open
close
Closes the currently open file.
void close(void)
eof
Returns a boolean value (true/false) indicating whether the
file has reached the EOF marker.
result // boolean; true or false
eof(void)
rewind
Resets the file read/write point to the beginning of the file.
void rewind(void)
name
Returns a string containing the name (and path, if it was
originally specified) of the currently open file.
result // string; file name
name(void)
write, writeln
write() places a series of one or more arguments to the file.
writeln() is identical to write() except that a newline
character is appended to the line.
result // integer; number of bytes
// written to file
write(item1[,itemN]) // data type; one or more
// variables or
// constants
read
Reads a text line from the file, returning it as a character
string. This function is illegal when the file is opened in
Binary mode.
result // string; text line from
// file
read(void)
readNumber
In ASCII mode, this function reads a sequence of characters
from the file, converting them to a single numeric value. In
Binary mode, a single integer value is read from the file.
result // number; a floating-point
// value
readNumber(void)
readVector
In ASCII mode, this function will read a sequence of
characters from the file, return them as a vector data type.
The data in the file should appear as space-separated,
floating-point numbers.
result // vector; the vector as it
// appears in the file
readVector(void)
parse
Read a line from the file, and returns a variable number of
elements representing the tokens of the line. Tokens are
separated by one of the characters provided in the character
string argument.
result // string[]; array of
// character strings
// representing
// tokens
parse(token) // string; a character
// string of tokens
// separators
nl
Writes a newline character to the file. This command is
illegal in Binary mode.
void nl(void)
linecount
When the file is opened in ASCII mode, this function returns
the number of text lines in the currently-open file. However,
in Binary mode, it returns the size, in bytes, of the file.
result // integer; line or byte
// count of file
linecount(void)
line
In ASCII mode, this function returns the current line number
in the file when no argument is provided. When a integer
value is provided that falls within the range of text lines in
the file, it will move the file pointer to the line number
indicated.
result // integer; current line
// number when
// optional parameter
// is omitted
line([linenumber]) // integer; the line number
// to which the file
// should be
// positioned
readInt
In ASCII mode, this function will read a sequence of
characters from the text file and return an integer data type.
In Binary mode, a single binary value of size integer will be
read from the file.
result // integer; an integer
// value from the file
readInt(void)
readByte
In ASCII mode, this function will return a single character
from the text file as a integer value. In Binary mode, a
single binary value of size unsigned char is read from the
file and returned as an integer value.
result // integer; single byte
// from the file
readByte(void)
writeNumber
In ASCII mode, the value provided is written into the text
file as a floating-point number in character format. In
Binary mode, a single binary value of size double is written
to the file.
result // integer; number of bytes
// written to file
writeNumber(value) // number; floating-point
// value
writeInt
In ASCII mode, the value provided is written into the text
file as an integer numeric value in character format. In
Binary mode, a single binary value of size integer is written
to the file
result // integer; number of bytes
// written to file
writeInt(value) // integer; the value to be
// written
writeByte
In ASCII mode, the integer value proved is written into the
text file as a character. In Binary mode, the provided value
is stored in the file as a single binary value of size
unsigned character.
result // integer; number of bytes
// written to file
writeByte(value) // integer; the value to be
// written
offset
Called without parameters, this method will return the current
byte offset of the file. Providing an integer value will
cause the file pointer to be placed at the specified offset in
the file, relative to an offset method. This optional offset
method can be one of: FROMSTART, which will position the file
from the beginning (and is the default when no method is
specified); FROMEND, which will position from the end of the
file; and FROMHERE, which assumes that the provided offset
value is relative to the current location of the pointer.
result // integer; current offset
// in file
offset([value // integer; offset to be
// used
[,method]]) // constant; FROMSTART,
// FROMEND or FROMHERE
Please refer to the numerous example LScripts supplied with
LightWave 3D for further examples of using the LScript File
Object Agent.User-created Object Agents
LScript provides an extension mechanism that allows software
prorammers to create new Object Agents. This support, and
the steps required to take advantage of it, are documented in
APPENDIX B: Extending LScript Shared
Libraries: User-Defined Object Agents.
Next Section
Previous Section
Table of Contents
Index
Errata
© 1996 Virtual Visions, Inc.
© 1997 NewTek, Inc.